<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>Integrating with other authentication systems | Elasticsearch Guide [7.7] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch Guide [7.7]">
<link rel="up" href="setting-up-authentication.html" title="User authentication">
<link rel="prev" href="kerberos-realm.html" title="Kerberos authentication">
<link rel="next" href="anonymous-access.html" title="Enabling anonymous access">
<meta name="DC.type" content="Learn/Docs/Elasticsearch/Reference/7.7">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="7.7">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<strong>IMPORTANT</strong>: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
<a href="../current/index.html">current release documentation</a>.
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="secure-cluster.html">Secure a cluster</a></span>
»
<span class="breadcrumb-link"><a href="setting-up-authentication.html">User authentication</a></span>
»
<span class="breadcrumb-node">Integrating with other authentication systems</span>
</div>
<div class="navheader">
<span class="prev">
<a href="kerberos-realm.html">« Kerberos authentication</a>
</span>
<span class="next">
<a href="anonymous-access.html">Enabling anonymous access »</a>
</span>
</div>
<div class="section xpack">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="custom-realms"></a>Integrating with other authentication systems<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/custom-realm.asciidoc">edit</a><a class="xpack_tag" href="/subscriptions"></a>
</h2>
</div></div></div>
<p>If you are using an authentication system that is not supported out-of-the-box
by the Elasticsearch security features, you can create a custom realm to interact with
it to authenticate users. You implement a custom realm as an SPI loaded security
extension as part of an ordinary elasticsearch plugin.</p>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="implementing-custom-realm"></a>Implementing a custom realm<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/custom-realm.asciidoc">edit</a>
</h3>
</div></div></div>
<p>Sample code that illustrates the structure and implementation of a custom realm
is provided in <a href="https://github.com/elastic/elasticsearch/tree/7.7/x-pack/qa/security-example-spi-extension" class="ulink" target="_top">https://github.com/elastic/elasticsearch/tree/7.7/x-pack/qa/security-example-spi-extension</a>. You can use this code as a starting point for creating your
own realm.</p>
<p>To create a custom realm, you need to:</p>
<div class="olist orderedlist">
<ol class="orderedlist">
<li class="listitem">
Extend <code class="literal">org.elasticsearch.xpack.security.authc.Realm</code> to communicate with your
authentication system to authenticate users.
</li>
<li class="listitem">
Implement the <code class="literal">org.elasticsearch.xpack.security.authc.Realm.Factory</code> interface in
a class that will be used to create the custom realm.
</li>
<li class="listitem">
Extend <code class="literal">org.elasticsearch.xpack.security.authc.DefaultAuthenticationFailureHandler</code> to
handle authentication failures when using your custom realm.
</li>
</ol>
</div>
<p>To package your custom realm as a plugin:</p>
<div class="olist orderedlist">
<ol class="orderedlist">
<li class="listitem">
<p>Implement an extension class for your realm that extends
<code class="literal">org.elasticsearch.xpack.core.security.SecurityExtension</code>. There you need to
override one or more of the following methods:</p>
<div class="pre_wrapper lang-java">
<pre class="programlisting prettyprint lang-java">@Override
public Map&lt;String, Factory&gt; getRealms() {
    ...
}</pre>
</div>
<p>The <code class="literal">getRealms</code> method is used to provide a map of type names to the <code class="literal">Factory</code> that
will be used to create the realm.</p>
<div class="pre_wrapper lang-java">
<pre class="programlisting prettyprint lang-java">@Override
public AuthenticationFailureHandler getAuthenticationFailureHandler() {
    ...
}</pre>
</div>
<p>The <code class="literal">getAuthenticationFailureHandler</code> method is used to optionally provide a
custom <code class="literal">AuthenticationFailureHandler</code>, which will control how the
Elasticsearch security features respond in certain authentication failure events.</p>
<div class="pre_wrapper lang-java">
<pre class="programlisting prettyprint lang-java">@Override
public List&lt;String&gt; getSettingsFilter() {
    ...
}</pre>
</div>
<p>The <code class="literal">Plugin#getSettingsFilter</code> method returns a list of setting names that should be
filtered from the settings APIs as they may contain sensitive credentials. Note this method is not
part of the <code class="literal">SecurityExtension</code> interface, it’s available as part of the elasticsearch plugin main class.</p>
</li>
<li class="listitem">
Create a build configuration file for the plugin; Gradle is our recommendation.
</li>
<li class="listitem">
Create a <code class="literal">META-INF/services/org.elasticsearch.xpack.core.security.SecurityExtension</code> descriptor file for the
extension that contains the fully qualified class name of your <code class="literal">org.elasticsearch.xpack.core.security.SecurityExtension</code> implementation
</li>
<li class="listitem">
Bundle all in a single zip file.
</li>
</ol>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="using-custom-realm"></a>Using a custom realm to authenticate users<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/custom-realm.asciidoc">edit</a>
</h3>
</div></div></div>
<p>To use a custom realm:</p>
<div class="olist orderedlist">
<ol class="orderedlist">
<li class="listitem">
<p>Install the realm extension on each node in the cluster. You run
<code class="literal">bin/elasticsearch-plugin</code> with the <code class="literal">install</code> sub-command and specify the URL
pointing to the zip file that contains the extension. For example:</p>
<div class="pre_wrapper lang-shell">
<pre class="programlisting prettyprint lang-shell">bin/elasticsearch-plugin install file:///&lt;path&gt;/my-realm-1.0.zip</pre>
</div>
</li>
<li class="listitem">
<p>Add a realm configuration of the appropriate realm type to <code class="literal">elasticsearch.yml</code>
under the <code class="literal">xpack.security.authc.realms</code> namespace.
You must define your realm within the namespace that matches the type defined
by the extension.
The options you can set depend on the settings exposed by the custom realm.
If you are configuring multiple realms, you should also explicitly set the
<code class="literal">order</code> attribute to control the order in which the realms are consulted during
authentication. You should make sure each configured realm has a distinct
<code class="literal">order</code> setting. In the event that two or more realms have the same <code class="literal">order</code>,
they will be processed in realm <code class="literal">name</code> order.</p>
<div class="important admon">
<div class="icon"></div>
<div class="admon_content">
<p>When you configure realms in <code class="literal">elasticsearch.yml</code>, only the
realms you specify are used for authentication. If you also want to use the
<code class="literal">native</code> or <code class="literal">file</code> realms, you must include them in the realm chain.</p>
</div>
</div>
</li>
<li class="listitem">
Restart Elasticsearch.
</li>
</ol>
</div>
</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="kerberos-realm.html">« Kerberos authentication</a>
</span>
<span class="next">
<a href="anonymous-access.html">Enabling anonymous access »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
